<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>t_open</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4>NAME</h4><blockquote>
t_open - establish a transport endpoint
</blockquote><h4>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="xti.h.html">xti.h</a>&gt; #include &lt;fcntl.h&gt;

int t_open(
    const char *name,
    int oflag,
    struct t_info *info)
</code>
</pre>
</blockquote><h4>DESCRIPTION</h4><blockquote>
<pre>
<P><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Parameters</b>
<th align=center><b>Before call</b>
<th align=center><b>After call</b>
<tr valign=top><td align=left>name
<td align=center>x
<td align=center>=
<tr valign=top><td align=left>oflag
<td align=center>x
<td align=center>=
<tr valign=top><td align=left>info-&gt
<td align=center>addr
<td align=center>/
<tr valign=top><td align=left>info-&gt
<td align=center>options
<td align=center>/
<tr valign=top><td align=left>info-&gt
<td align=center>tsdu
<td align=center>/
<tr valign=top><td align=left>info-&gt
<td align=center>etsdu
<td align=center>/
<tr valign=top><td align=left>info-&gt
<td align=center>connect
<td align=center>/
<tr valign=top><td align=left>info-&gt
<td align=center>discon
<td align=center>/
<tr valign=top><td align=left>info-&gt
<td align=center>servtype
<td align=center>/
<tr valign=top><td align=left>info-&gt
<td align=center>flags
<td align=center>/
</table>
</pre>
<p>
The
<i>t_open()</i>
function must be called as the first step in the initialisation of a
transport endpoint.
This function establishes a transport endpoint by supplying a
transport provider identifier that indicates a particular transport
provider (that is, transport protocol) and returning a file descriptor
that identifies that endpoint.
<p>
The argument
<I>name</I>
points to a transport provider identifier and
<I>oflag</I>
identifies any open flags (as in
<i><a href="../xsh/open.html">open()</a></i>).
The argument
<I>oflag</I>
is constructed from O_RDWR optionally bitwise inclusive-OR'ed
with O_NONBLOCK.
These flags are defined by the header
<B>&lt;fcntl.h&gt;</B>.
The file descriptor returned by
<i>t_open()</i>
will be used by all subsequent functions
to identify the particular local transport endpoint.
<p>
This function also returns various default characteristics of
the underlying transport protocol
by setting fields in the
<B>t_info</B>
structure.
This argument points to a
<B>t_info</B>
which contains the following
members:
<pre>
<code>
t_scalar_t addr;      /* max size of the transport protocol address */
t_scalar_t options;   /* max number of bytes of                     */
                      /* protocol-specific options                  */
t_scalar_t tsdu;      /* max size of a transport service data       */
                      /* unit (TSDU)                                */
t_scalar_t etsdu;     /* max size of an expedited transport         */
                      /* service data unit (ETSDU)                  */
t_scalar_t connect;   /* max amount of data allowed on              */
                      /* connection establishment functions         */
t_scalar_t discon;    /* max amount of data allowed on              */
                      /* t_snddis() and t_rcvdis() functions        */
t_scalar_t servtype;  /* service type supported by the              */
                      /* transport provider                         */
t_scalar_t flags;     /* other info about the transport provider    */
</code>
</pre>
<br>
<p>
The values of the fields have the following meanings:
<dl compact>

<dt><I>addr</I><dd>A value greater than zero (T_NULL) indicates the maximum
size of a transport protocol address
and a value of -2 (T_INVALID)
specifies that the transport provider does not provide user
access to transport protocol addresses.

<dt><I>options</I><dd>A value greater than zero (T_NULL) indicates the maximum
number of bytes of protocol-specific options supported by the
provider,
and a value of -2 (T_INVALID) specifies that the transport provider
does not support user-settable options.

<dt><I>tsdu</I><dd>A value greater than zero (T_NULL) specifies
the maximum size of a transport service
data unit (TSDU);
a value of zero (T_NULL) specifies that the
transport provider does not support the concept of
TSDU,
although it does support the sending of a data stream with no
logical boundaries preserved across a connection;
a value of -1 (T_INFINITE)
specifies that there is no limit to the size of a
TSDU;
and a value of -2 (T_INVALID)
specifies that the transfer of normal data is
not supported by the transport provider.

<dt><I>etsdu</I><dd>A value greater than zero (T_NULL) specifies
the maximum size of an expedited transport
service data unit (ETSDU);
a value of zero (T_NULL) specifies that the
transport provider does not support the concept of ETSDU,
although it does support the sending of an expedited data stream with no
logical boundaries preserved across a connection;
a value of -1 (T_INFINITE) 
specifies that there is no limit on the size of an
ETSDU;
and a value of -2 (T_INVALID)
specifies that the transfer of expedited data is
not supported by the transport provider.
Note that the semantics of expedited data may be quite
different for different transport providers
(see
<xref href=istpi></xref>
and
<xref href=ipsi></xref>).

<dt><I>connect</I><dd>A value greater than zero (T_NULL) specifies
the maximum amount of data that may be associated with
connection establishment functions,
and a value of -2 (T_INVALID)
specifies that the transport provider does not
allow data to be sent with connection establishment functions.

<dt><I>discon</I><dd>If the T_ORDRELDATA bit in flags is clear,
a value greater than zero (T_NULL) specifies
the maximum amount of data that may be associated with the
<i><a href="t_snddis.html">t_snddis()</a></i>
and
<i><a href="t_rcvdis.html">t_rcvdis()</a></i>
functions,
and a value of -2 (T_INVALID)
specifies that the transport provider does not
allow data to be sent with the abortive release functions.
If the T_ORDRELDATA bit is set in flags, a value
greater than zero (T_NULL) specifies the maximum number of octets
that may be associated with the 
<i><a href="t_sndreldata.html">t_sndreldata()</a></i>,
<i><a href="t_rcvreldata.html">t_rcvreldata()</a></i>,
<i><a href="t_snddis.html">t_snddis()</a></i>
and 
<i><a href="t_rcvdis.html">t_rcvdis()</a></i>
functions.

<dt><I>servtype</I><dd>This field specifies the service type supported by the transport provider,
as described below.

<dt><I>flags</I><dd>This is a bit field used to specify other information about the 
communications provider.  If the T_ORDRELDATA bit is set,
the communications provider supports user data to be sent
with an orderly release.
If the T_SENDZERO bit is set in flags, this indicates the underlying
transport provider supports the sending of zero-length TSDUs.
See
<xref href=istpi></xref>
for a discussion of the separate issue of zero-length fragments
within a TSDU.

</dl>
<p>
If a transport user is concerned with protocol independence, the above
sizes may be accessed to determine how large the buffers must be
to hold each piece of information.
Alternatively, the
<i><a href="t_alloc.html">t_alloc()</a></i>
function may be used to allocate these buffers.
An error will result if a transport user exceeds the allowed
data size on any function.
<p>
The
<I>servtype</I>
field of
<I>info</I>
specifies one of the following values on return:
<dl compact>

<dt>T_COTS<dd>The transport provider supports a connection-mode service but
does not support the optional orderly release facility.

<dt>T_COTS_ORD<dd>The transport provider supports a connection-mode service with
the optional orderly release facility.

<dt>T_CLTS<dd>The transport provider supports a connectionless-mode service.
For this service type,
<i>t_open()</i>
will return -2 (T_INVALID) for
<I>etsdu</I>,
<I>connect</I>
and
<I>discon</I>.

</dl>
<p>
A single transport endpoint may support only one of the above
services at one time.
<p>
If
<I>info</I>
is set to
a null pointer
by the transport user, no protocol information is
returned by
<i>t_open()</i>.
</blockquote><h4>VALID STATES</h4><blockquote>
T_UNINIT
</blockquote><h4>ERRORS</h4><blockquote>
On failure,
<I>t_errno</I>
is set to the following:
<dl compact>

<dt>[TBADFLAG]<dd>An invalid flag is specified.

<dt>[TBADNAME]<dd>Invalid transport provider name.

<dt>[TPROTO]<dd>This error indicates that a communication problem has been detected between
XTI and the transport provider for which there is no other suitable XTI
error
<I>(t_errno)</I>.

<dt>[TSYSERR]<dd>A system error has occurred during execution of this function.

</dl>
</blockquote><h4>RETURN VALUES</h4><blockquote>
A valid file descriptor is returned upon successful completion.  Otherwise,
a value of -1 is returned and
<I>t_errno</I>
is set to indicate an error.
</blockquote><h4>SEE ALSO</h4><blockquote>
<i><a href="../xsh/open.html">open()</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
